Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / Using Transform Objects

Setting Up Hit-Test Parameters

QuickDraw GX provides a pair of functions (GXGetTransformHitTest, GXSetTransformHitTest) that get and set the hit-test parameters of a specified transform, and another pair (GXGetShapeHitTest, GXSetShapeHitTest) that get and set the hit-test parameters of the transform associated with a specified shape.

The hit-test parameters are used by the functions GXHitTestShape and GXHitTestPicture. Before calling either function, you set up the shape-parts mask and define a tolerance, and assign them both to the transform object of the shape you are going to hit-test. The shape-parts mask consists of values from the gxShapeParts enumeration; see Table 6-1 on page 6-12 for descriptions of the individual values.

The GXHitTestShape and GXHitTestPicture functions return, in addition to an indication of which shape parts were hit during a hit-test, a distance from the hit point to one of the hit parts. If only one shape part was hit, the distance is the distance from the hit point to the nearest point on the hit part. But if more than one part was hit (for example, if a hit corresponded to both the bounding rectangle and the shape geometry), the distance returned is the distance to the first shape part--in order of processing by the function-- that was hit. The order in which shape parts are processed is the order in which they appear in the gxShapeParts enumeration. Thus, if both bounding rectangle and geometry are tested for, and if both are hit, the distance returned is the distance to the bounding rectangle. You can use the processing order to set up the shape-parts mask to make sure that GXHitTestShape and GXHitTestPicture return the exact distance information you need.

The following example sets the shape-parts mask (mask) to include both the geometry and the corner points of the shape aShape. It also sets the tolerance to 0, meaning that if a hit point is any distance outside of the shape geometry or corner points, it is not considered a hit.

gxShapePart    mask = gxGeometryPart | gxCornerPointPart;
GXSetShapeHitTest(aShape, mask, 0);

For more information about shape parts and tolerance as a transform object property, see the section "Hit-Test Parameters" on page 6-11. For information about hit-testing with GXHitTestShape, see the chapter "Shape Objects" in this book. For information about hit-testing with GXHitTestPicture, see the picture shapes chapter of Inside Macintosh: QuickDraw GX Graphics.

The GXGetTransformHitTest function is described on page 6-78;
the GXSetTransformHitTest function is described on page 6-79. The GXGetShapeHitTest function is described on page 6-80; the GXSetShapeHitTest function is described on page 6-81.